Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
Loading...
Searching...
No Matches
io_uri.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2019 Roc authors
3 *
4 * This Source Code Form is subject to the terms of the Mozilla Public
5 * License, v. 2.0. If a copy of the MPL was not distributed with this
6 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 */
8
9//! @file roc_address/io_uri.h
10//! @brief Audio file or device URI.
11
12#ifndef ROC_ADDRESS_IO_URI_H_
13#define ROC_ADDRESS_IO_URI_H_
14
15#include "roc_core/stddefs.h"
16
17namespace roc {
18namespace address {
19
20//! Audio file or device URI.
21struct IoURI {
22 //! Initialize empty URI.
24
25 //! Returns true if the URI is empty.
26 bool is_empty() const;
27
28 //! Returns true if the scheme is "file".
29 bool is_file() const;
30
31 //! Returns true if the scheme is "file" and the path is "-".
32 bool is_special_file() const;
33
34 enum {
35 // An estimate maximum length of encoded URI.
36 MaxLength = 1280
37 };
38
39 //! URI scheme.
40 //! May be "file" or device type, e.g. "alsa".
41 char scheme[16];
42
43 //! URI path.
44 //! May be device name or file path depending on scheme.
45 char path[1024];
46};
47
48//! Parse IoURI from string.
49//!
50//! The URI should be in one of the following forms:
51//!
52//! - DEVICE_TYPE://DEVICE_NAME (audio device)
53//!
54//! - file:///ABS/PATH (file, absolute path)
55//! - file://localhost/ABS/PATH (equivalent to the above)
56//! - file:/ABS/PATH (equivalent to the above)
57//!
58//! - file:REL/PATH (file, relative path)
59//!
60//! - file://- (stdin or stdout)
61//! - file:- (equivalent to the above)
62//!
63//! Where:
64//! - DEVICE_TYPE specifies the audio system name, e.g. "alsa" or "pulse"
65//! - DEVICE_NAME specifies the audio device name, e.g. ALSA card name
66//! - /ABS/PATH specifies an absolute file path
67//! - REL/PATH specifies a relative file path
68//!
69//! Examples:
70//! - alsa://card0
71//! - file:///home/user/somefile.wav
72//! - file://localhost/home/user/somefile.wav
73//! - file:/home/user/somefile.wav
74//! - file:./somefile.wav
75//! - file:somefile.wav
76//! - file://-
77//! - file:-
78//!
79//! The URI syntax is defined by RFC 8089 and RFC 3986.
80//!
81//! The path part of the URI is percent-decoded.
82//!
83//! The RFC allows usages of file:// URIs both for local and remote files. Local files
84//! should use either empty or special "localhost" hostname. This parser only recognizes
85//! these two variants; other hostnames will be considered as a parsing error.
86//!
87//! The RFC allows only absolute paths in file:// URIs. This parser additionally allows
88//! relative paths, but only in the "file:" form (without "//"). Relative paths are not
89//! allowed in the "file://" form (with "//") because it would lead to an ambiguity.
90//!
91//! This parser also allows a non-standard "-" path for stdin/stdout.
92//!
93//! This parser does not try to perform full URI validation. For example, it does not
94//! check that path contains only allowed symbols. If it can be parsed, it will be.
95bool parse_io_uri(const char* str, IoURI& result);
96
97//! Format IoURI to string.
98//!
99//! Formats a normalized form of the URI.
100//!
101//! The path part of the URI is percent-encoded if necessary.
102//!
103//! This function always uses the "file:" form (without "//") for files because this is
104//! the only form that supports both absolute and relative paths.
105//!
106//! @returns
107//! true on success or false if the buffer is too small.
108bool format_io_uri(const IoURI& uri, char* buf, size_t buf_size);
109
110} // namespace address
111} // namespace roc
112
113#endif // ROC_ADDRESS_IO_URI_H_
bool parse_io_uri(const char *str, IoURI &result)
Parse IoURI from string.
bool format_io_uri(const IoURI &uri, char *buf, size_t buf_size)
Format IoURI to string.
Root namespace.
Commonly used types and functions.
Audio file or device URI.
Definition: io_uri.h:21
bool is_file() const
Returns true if the scheme is "file".
bool is_special_file() const
Returns true if the scheme is "file" and the path is "-".
char path[1024]
URI path. May be device name or file path depending on scheme.
Definition: io_uri.h:45
bool is_empty() const
Returns true if the URI is empty.
IoURI()
Initialize empty URI.
char scheme[16]
URI scheme. May be "file" or device type, e.g. "alsa".
Definition: io_uri.h:41